All Databases Inside Mac - AppleEvents

Getting Data Out of a Descriptor List

You can use the AECountItems function to count the number of items in a

descriptor list, and you can use AEGetNthDesc or AEGetNthPtr to get a

descriptor record or its data out of a descriptor list.

The Open Documents event contains a direct parameter that specifies the list

of documents to open. The list of documents is contained in a

descriptor list. After extracting the descriptor list from the parameter,

you can determine the number of items in the list and then extract each

descriptor record from the descriptor list.

For example, when your handler receives an Open Documents event, you can

use the AEGetParamDesc function to return the direct parameter as a

descriptor list. You can then use AECountItems to return the number of

descriptor records in the list.

AppleEvent theAppleEvent;

AEDescList docList;

long itemsInList;

OSErr myErr;

myErr = AEGetParamDesc(& theAppleEvent, keyDirectObject, typeAEList,

& docList);

myErr = AECountItems(& docList, & itemsInList);

The AEGetParamDesc function returns in the docList variable the

descriptor list from the direct parameter of the Open Documents event. You

specify this list to the AECountItems function.

You specify the descriptor list whose items you want to count in the first

parameter to AECountItems. The Apple Event Manager returns the

number of items in the list in the second parameter. When extracting the

descriptor records from a list, you often use the number of items as a loop

index. Here's an example:

for (index = 1; index <= itemsInList; index++) {

//for each descriptor record in the list, get its data

}

The format of the descriptor records in a descriptor list is private to the

Apple Event Manager. You must use the AEGetNthPtr or AEGetNthDesc

function to extract descriptor records from a

descriptor list.

You specify the descriptor list that contains the desired descriptor records

and an index as parameters to the AEGetNthPtr function. The index

represents a specific descriptor record in the descriptor list. AEGetNthPtr

returns the data from the descriptor  record represented by the specified  index
.

You also specify the descriptor type the function should use to return the data,

a buffer to store the data, and the size of this buffer. The AEGetNthPtr

function returns the keyword of the parameter, the descriptor type of the

returned data, and the actual size of the data, and it places the requested data in

the specified buffer.

Here's an example that uses the AEGetNthPtr function to extract an item

from the descriptor list in the direct parameter of the

Open Documents event.

myErr = AEGetNthPtr(& docList, index, typeFSS, &keywd, & returnedType,

& myFSS, sizeof( myFSS), & actualSize);

The docList variable specifies the descriptor list from the direct parameter of

the Open Documents event. The index variable specifies the index of the

descriptor record to extract. You can use the typeFSS descriptor type, as in

this example, to specify that the data be returned as a file system specification

record (FSSpec). The Apple Event Manager automatically coerces the

original data type of the descriptor record from an alias record to a file system

specification record. The AEGetNthPtr function returns the keyword of the

parameter in the keywd variable. The function returns in the returnedType

variable the descriptor type of the resulting data.

You specify a buffer to hold the desired data and the size (in bytes) of the

buffer as parameters to the AEGetNthPtr function. In this example, the

myFSS variable specifies the buffer. The function returns the actual size of

the data in the actualSize variable. If this size is larger than the size of the

buffer you provided, you know that you didn't get all of the data for the

descriptor record.

The following program shows a more complete example of extracting the

items from a descriptor list in the Open Documents event.

// Extracting items from a descriptor list

// Assuming inclusion of

#include <AppleEvents.h>

void DoError (OSErr myErr);

OSErr MyOpenFile (FSSpec * myFSS);

long index, itemsInList;

AEDescList docList;

AEKeyword keywd;

DescType returnedType;

FSSpec myFSS;

Size actualSize;

OSErr myErr;

for ( index=1; index<= itemsInList; index++) {

myErr = AEGetNthPtr(& docList, index, typeFSS, &keywd,

& returnedType, (Ptr)& myFSS,

sizeof( myFSS), & actualSize);

if ( myErr)

DoError( myErr);

myErr = MyOpenFile(& myFSS);

if ( myErr)

DoError( myErr);

}

myErr = AEDisposeDesc(& docList);

Referenced by (8):